Skip to content

docs(updating): document @ionic/core package exports field in v9 upgrade guide#4523

Merged
ShaneK merged 1 commit into
major-9.0from
feat/esm
Jun 1, 2026
Merged

docs(updating): document @ionic/core package exports field in v9 upgrade guide#4523
ShaneK merged 1 commit into
major-9.0from
feat/esm

Conversation

@ShaneK
Copy link
Copy Markdown
Member

@ShaneK ShaneK commented May 29, 2026

Adds a "Package Exports" subsection to the Ionic 9 upgrade guide, related to this PR: ionic-team/ionic-framework#31180

@ShaneK ShaneK requested a review from a team as a code owner May 29, 2026 20:54
@ShaneK ShaneK requested review from BenOsodrac and removed request for a team May 29, 2026 20:54
@vercel
Copy link
Copy Markdown

vercel Bot commented May 29, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
ionic-docs Ready Ready Preview, Comment May 29, 2026 9:03pm

Request Review

Copy link
Copy Markdown
Contributor

@thetaPC thetaPC left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

ShaneK added a commit to ionic-team/ionic-framework that referenced this pull request Jun 1, 2026
Issue number: resolves #30982, resolves #30686, resolves #30730

---------

## What is the current behavior?

Core's package.json has no `exports` field. Webpack and Vite handle that
fine, but Node's strict ESM resolver ignores nested package.json files
and refuses directory imports. So when the built `@ionic/angular` bundle
does `import { defineCustomElements } from '@ionic/core/loader'` or
`import { componentOnReady } from '@ionic/core/components'`, anything
running under Node ESM (Angular 21's default Vitest builder, raw Node,
etc.) throws `ERR_UNSUPPORTED_DIR_IMPORT`. All three resolved issues
have the same root problem

## What is the new behavior?

Core's package.json now declares an `exports` map that covers every
directory in `files` with explicit `index.js` resolution where directory
imports happen, and wildcards for the deep paths

## Does this introduce a breaking change?

- [x] Yes
- [ ] No

When you add `exports` to a package.json, it becomes an allowlist. This
means that every undocumented import path will break unless you're using
`moduleResolution: node`

Related docs PR: ionic-team/ionic-docs#4523

## Other information

Apps already on `moduleResolution: "bundler"` (Angular 17+ default, Vite
default) pick up the fix automatically. Apps on classic
`moduleResolution: "node"` keep working through the legacy fields and
are unaffected.

Current dev build:
```
8.8.9-dev.11780086312.13aac420
```
@ShaneK ShaneK merged commit a52dd0b into major-9.0 Jun 1, 2026
4 checks passed
@ShaneK ShaneK deleted the feat/esm branch June 1, 2026 13:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants